Bug Proofing Visual Basic: A Guide to Error Handling and Prevention
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471323519
Publication Date: 11/01/98

Some programmers place a routine’s comments after its declaration like this:

Public Sub SelectionSort(ByRef numbers() As Integer)

‘ ************************************************
‘ Purpose: Sort an array of numbers.
‘    :
‘ More comments
‘    :
‘ ************************************************

   ‘ The code starts here
        :

It doesn’t much matter where you put the comments, as long as they are immediately next to the routine and the developers on the project are consistent.

Comment Event Handlers

Event handlers are generally similar to routines, but they have a few key differences. The parameters are specified by the event’s definition, so you do not really need to document input and output values in an event handler unless it has unusual side effects. Developers are familiar with the parameters of the more common event handlers. Those who have questions can consult the Visual Basic online help.

Event handlers are invoked by Visual Basic, not other code in the application, so they must never raise errors. The program cannot trap errors generated by code that it does not call directly. If an event handler raises an error, the program crashes. For this reason, event handler comments do not need an errors section. Assertions are still useful in event handlers, though, so the comments should still contain an asserts section.

Finally, the purpose of the event handler is obviously to handle an event. Do not merely repeat that in the purpose section of the comment. Instead, explain what the routine does about the event. State what triggered the event and explain what that means to the program. Do not state, “Handle the user’s mouse move event.” Instead, say, “If the user is dragging a node, move it to this new position.”

The following code shows an example event handler header. Appendix B, “Header Comment Templates,” contains a blank template for an event handler header comment. You can download the blank template from the book’s Web page at www.vb-helper.com/err.htm and paste it into your code.

‘ ************************************************

‘ Purpose: The user has clicked the color
‘          selection area. Display the selected
‘          color.
‘
‘ Method:  Use the Mod operator to determine the
‘          row and cloumn clicked. Display the
‘          corresponding color in the Colors array.
‘
‘ Outputs: Updates the global value SelectedColor.
‘
‘ Asserts:
‘    The number of colors displayed should be
‘    either 16 or 256.
‘
‘ Developer           Date     Comments
‘ ---------           -------- --------
‘ Mike Johnson         8/20/97 Initial creation.
Private Sub ColorArea_MouseUp(Button As Integer, _
    Shift As Integer, X As Single, Y As Single)

        :

Give Context, Not Content

Use comments that provide context to help the reader understand your code. Do not simply repeat what the code does. The comment in the following code is overkill. Any experienced programmer can tell what this statement does.

employee = employee + 1   ‘ Add 1 to employee.

Instead, use comments that explain why the code is doing what it does. Make it easier for a programmer of average experience to follow your logic.

employee = employee + 1   ‘ Consider the next employee in the 
                          ‘ array.

Comment Portability Issues

Comment code that may break if some other part of the system changes. If something on your computer changes, you can look for these comments to see where bugs may have appeared.

Comment code that may not be portable to other operating systems such as Windows NT, Windows 95, and Windows 3.11. Routines that use API functions, system files, or other system-related objects may stop working when you change or upgrade the operating system.

Comment code that may not work with different software versions such as 16-bit Visual Basic 4 or 32-bit Visual Basic 6. Comment code that may not work with different versions of third-party software such as custom controls or database libraries you may have purchased.

These are all places the code is likely to fail when any of these external components change. Make it easy to find them so you can inspect them quickly.

Comment Plainly

Write your comments in plain, everyday language. The goal is to make comments as easy to read as possible, not to save a few keystrokes.

•  Do not write with a stilted corporate style.

•  Do not use abbreviations. If a comment is too long, continue it on the next line.

•  Do not use acronyms unless they are obvious in your industry.

•  Use complete sentences.

•  Use proper punctuation.

•  Use proper capitalization.

Don’t Comment Continued Statements

Visual Basic does not allow you to place comments on a line after a line continuation character. To place a comment on a statement that is continued across more than one line, you must put the comment on the last line. That makes it harder to understand that the comment applies to the whole statement.

numbers(i) = _

    numbers(smallest_index) + _
    i ‘ This is a strange place for a comment.

To make this type of comment easier to read, place it before the continued statement.

‘ This is a much better place for the comment.
numbers(i) = _
    numbers(smallest_index) + _

    i

Don’t Remove Comments

Do not remove comments when you fix bugs or make enhancements, just add to them. Do not remove the old code either, just comment it out. If you later discover that a bug fix was incorrect, you can quickly replace the previous code.

The descriptive comments and commented code give the routine’s history. One important use for this history is to determine which routines are buggy. If a lot of bugs have been fixed in a routine, it is likely to contain other bugs.

This is somewhat contrary to intuition. You might think a larger percentage of the bugs have been removed from the routine than from other routines that have had fewer bugs in the past. Actually, a high bug count indicates that the routine probably has some larger design or conceptual flaw. If a routine contains too many bug fixes, it is often better to rewrite it from scratch instead of continuing to patch it.

Format Comments Nicely

Neatness counts. Remember, the intent is to make comments as easy to read as possible. Ugly formatting makes the reader work harder to understand the comments and distracts from the more important task of understanding the code. Which of the following sets of comments is easier to read?

‘ Comments ragged right.
For Each ctl In Controls ‘ Examine the controls.
    If TypeName(ctl) = “TextBox” Then ‘ If it is a TextBox:
        If ctl.Text = “” Then ‘ If the value is missing:
            MsgBox “Enter ” & ctl.Name    ‘ Tell the user it’s required.
            ctl.SetFocus ‘ Return to the field.
            Exit Sub ‘ Let the user enter a value.
        End If
    End If
Next ctl

‘ Comments neatly aligned.
For Each ctl In Controls                 ‘ Examine the controls.
    If TypeName(ctl) = “TextBox” Then    ‘ If it is a TextBox:
        If ctl.Text = “” Then            ‘ If the value is missing:
            MsgBox “Enter ” & ctl.Name   ‘ Tell the user it's required.

            ctl.SetFocus                  ‘ Return to the field.

            Exit Sub                     ‘ Let the user enter a value.

        End If
    End If

Next ctl